Configuring Bundle Identifier, Version, and Build Number in iOS

Course: iOS App Development

Topic: Configuring Bundle Identifier, Version, and Build Number

Course Link: iOS Training at JustAcademy

Demo Link: Register for a Free Course Demo

Website: JustAcademy Official Website

1. Introduction

Every iOS application requires identification and version information before it can be installed, tested, archived, or distributed. In Xcode, three important configuration values control how an application is identified and how its releases are tracked: the Bundle Identifier, Version Number, and Build Number.

These settings are essential throughout the iOS development lifecycle. They help iOS distinguish one application from another, allow developers to manage app releases, and help App Store Connect and TestFlight identify individual uploaded builds.

For example, an application named ShopEasy may use the following configuration:

Bundle Identifier: com.example.shopeasy
Version:           1.0.0
Build:             1

Although these values are often configured together in Xcode, each serves a different purpose and follows different rules.

2. Learning Objectives

• Understand the purpose of an iOS Bundle Identifier.
• Learn reverse-domain naming conventions.
• Understand the difference between app version and build number.
• Configure application identity settings in Xcode.
• Manage version updates during development.
• Understand how bundle information relates to Info.plist and build settings.
• Prepare correct version information for TestFlight and App Store distribution.
• Identify and troubleshoot common configuration errors.

3. What Is a Bundle Identifier?

A Bundle Identifier is a unique string that identifies an application within Apple's software ecosystem. It allows iOS, Xcode, signing services, and App Store Connect to recognize a specific application.

Bundle identifiers commonly follow the reverse-domain naming convention. This means the domain name is written in reverse order, followed by the application name.

Example

Company Domain: example.com
Application:   ShopEasy
Bundle ID:     com.example.shopeasy

Another example is:

com.justacademy.studentapp

Here:

• com: A commonly used top-level naming prefix.
• justacademy: The organization or developer identifier.
• studentapp: The application-specific name.

3.1 Why Is the Bundle Identifier Important?

• Application identity: It uniquely identifies an app to the operating system.
• App installation: It helps the system distinguish applications installed on a device.
• Code signing: It is associated with the App ID and signing configuration.
• Push notifications: It is relevant when configuring application identifiers and push notification capabilities.
• App Store distribution: It connects the Xcode application target with its App Store Connect record.
• App services: It is used when configuring services such as associated domains, iCloud, and other capabilities.

3.2 Bundle Identifier Naming Rules

When creating a bundle identifier, follow these important conventions:

• Use a reverse-domain structure, such as com.company.application.
• Use letters, numbers, periods, and hyphens.
• Avoid spaces and special characters that are not supported.
• Use a consistent naming convention across related projects.
• Make sure the identifier is unique for the intended application.
• Remember that bundle identifiers are case-sensitive.

Examples of Bundle Identifiers

4. What Is an App Version Number?

The Version Number represents the release version of an application. It communicates which version of the app is being distributed to users.

For example:

1.0.0
1.1.0
1.2.0
2.0.0

Version numbers commonly follow Semantic Versioning-style conventions using three components:

MAJOR.MINOR.PATCH

• Major: Indicates a significant release, major redesign, or substantial changes.
• Minor: Indicates new features or functionality that generally preserve existing compatibility.
• Patch: Indicates smaller fixes, maintenance updates, or bug fixes.

4.1 Version Number Examples

4.2 CFBundleShortVersionString

In the application bundle's information property list, the release version is represented by the key CFBundleShortVersionString.

This is the user-facing version string. For App Store applications, it is the version users can see in the app's store information.

Example:

CFBundleShortVersionString = 1.2.0

Apple documents this value as a string containing three period-separated numeric components, such as 1.2.0.

5. What Is a Build Number?

A Build Number identifies a particular compiled iteration of an application. Developers use it to distinguish individual builds created during development, testing, and distribution.

For example, a development team may create several builds without changing the public release version:

Version: 1.0.0
Build:   1

Version: 1.0.0
Build:   2

Version: 1.0.0
Build:   3

All three builds belong to version 1.0.0, but each represents a different build iteration.

5.1 CFBundleVersion

The build number is represented by the CFBundleVersion key in the application bundle's information property list.

Example:

CFBundleVersion = 3

Apple defines this as the build version that identifies an iteration of the bundle. It is generally maintained as a period-separated numeric string.

5.2 Why Is the Build Number Important?

• Distinguishes multiple builds of the same app version.
• Helps developers track testing releases.
• Identifies uploaded builds in App Store Connect and TestFlight.
• Supports debugging and crash-report investigation.
• Helps teams identify which code changes are included in a particular build.
• Prevents confusion when several development builds are distributed.

6. Difference Between Bundle Identifier, Version, and Build Number

7. How to Configure the Bundle Identifier in Xcode

Xcode provides an interface for configuring application identity. Follow these steps to set the Bundle Identifier.

Step 1: Open the Xcode Project

• Launch Xcode on your Mac.
• Open an existing iOS application project or create a new project.
• Wait for Xcode to load the project files.

Step 2: Select the Project

• Click the project name in the Project Navigator.
• Select the relevant project configuration.
• Under Targets, select the iOS application target.

Step 3: Open the General Tab

• Click the General tab in the project editor.
• Locate the Identity section.
• Find the Bundle Identifier field.

Step 4: Enter the Bundle Identifier

Enter a unique identifier for your application.

com.justacademy.studentapp

Step 5: Verify the Identifier

• Check spelling and capitalization.
• Ensure the identifier follows the reverse-domain convention.
• Confirm it matches the intended App ID when configuring signing and distribution.

8. How to Configure Version and Build Number in Xcode

Xcode provides separate fields for the release version and build number.

Step 1: Select the Application Target

Open the project and select the main iOS application target under Targets.

Step 2: Open General Settings

Navigate to the General tab and locate the Identity section.

Step 3: Configure the Version

Enter the release version in the Version field.

Version: 1.0.0

Step 4: Configure the Build Number

Enter the build number in the Build field.

Build: 1

Step 5: Save and Verify

Review the values and build the application to confirm that the project configuration is valid.

9. Understanding Bundle Configuration in Info.plist

The Information Property List, commonly known as Info.plist, contains configuration information about an application bundle. It describes important application characteristics, including its identifier and version information.

The three important keys are:

9.1 Example Info.plist Configuration

The following is an illustrative property-list configuration showing the relevant values:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIdentifier</key>
    <string>com.example.shopeasy</string>

    <key>CFBundleShortVersionString</key>
    <string>1.0.0</string>

    <key>CFBundleVersion</key>
    <string>1</string>
</dict>
</plist>

Important: Many modern Xcode projects manage these values through build settings and generate or process the final Info.plist automatically. Avoid creating duplicate keys or manually editing generated files without understanding the project's configuration.

10. Understanding Xcode Build Settings

Xcode uses build settings to control how the application is compiled and packaged. The bundle identifier, version, and build number are commonly connected to the following build settings:

10.1 Example Build Settings

PRODUCT_BUNDLE_IDENTIFIER = com.example.shopeasy
MARKETING_VERSION = 1.0.0
CURRENT_PROJECT_VERSION = 1

These settings can be inspected in the target's Build Settings tab. Depending on the project, they may be configured directly or through an .xcconfig file.

11. Managing Version Updates During Development

During development, an application may go through multiple iterations. Developers should maintain a consistent approach to updating the release version and build number.

Example Development Sequence

This is an illustrative sequence. Actual build numbers should follow the project's distribution and release process.

12. Configuring Version and Build Through an .xcconfig File

Xcode configuration files, also known as .xcconfig files, allow developers to manage build settings outside the project editor. They are useful when a project has multiple environments or targets.

Example: AppConfig.xcconfig

PRODUCT_BUNDLE_IDENTIFIER = com.example.shopeasy
MARKETING_VERSION = 1.0.0
CURRENT_PROJECT_VERSION = 1

Developers can create separate configuration files for Debug and Release builds when different configuration values are required.

Benefits of .xcconfig Files

• Keep build settings organized.
• Make configuration changes easier to review.
• Support multiple build configurations.
• Reduce repeated configuration across targets.
• Help teams maintain consistent project settings.

13. Managing Multiple Targets and Bundle Identifiers

A single Xcode project can contain multiple targets. For example, an application may include a main app, a notification service extension, and a widget extension.

Each executable target generally requires its own appropriate bundle identifier. Embedded extensions commonly use the main application's bundle identifier as a prefix.

Example

Main App:
com.example.shopeasy

Notification Extension:
com.example.shopeasy.notification

Widget Extension:
com.example.shopeasy.widget

Correct target identifiers are important for code signing, provisioning, and application services. Check each target separately rather than assuming that changing the main app target updates every extension automatically.

14. Bundle Identifier and Code Signing

Code signing verifies the identity of an application and helps ensure that the app has been signed using an appropriate development or distribution identity.

The bundle identifier is closely connected to the App ID used by Apple's signing and provisioning system.

Important Relationships

• The bundle identifier in the Xcode target should match the intended App ID.
• The provisioning profile must support the application's identifier and required capabilities.
• The selected signing team must have access to the required signing resources.
• Capabilities such as Push Notifications and Associated Domains may require corresponding App ID configuration.

A mismatch between the target's bundle identifier and the signing configuration can cause signing or provisioning errors.

15. Preparing Version and Build Information for TestFlight

TestFlight is Apple's platform for distributing beta versions of iOS applications to internal and external testers.

Before uploading a build, developers should verify the application identifier, release version, and build number.

Recommended Workflow

1. Open the iOS project in Xcode.
2. Verify the Bundle Identifier.
3. Set the appropriate Version Number.
4. Increment the Build Number for the new upload.
5. Select an appropriate archive destination.
6. Choose Product and then Archive.
7. Open the Organizer window after the archive is created.
8. Validate the archive and follow the distribution workflow.
9. Upload the build to App Store Connect.
10. Verify the uploaded build and its processing status.

When uploading successive builds for testing, use a new build number for each upload. Keep the release version consistent when the builds belong to the same app version.

16. Preparing Version Information for App Store Submission

Before submitting an iOS application to the App Store, developers should confirm that the version and build information are consistent between Xcode and App Store Connect.

Pre-submission Checklist

• Confirm that the Bundle Identifier matches the correct App Store Connect app record.
• Check that the Version Number is correct.
• Use a valid Build Number for the uploaded build.
• Confirm the app's signing configuration.
• Verify that the archive contains the expected application target.
• Check that the uploaded build has completed processing.
• Review the release information before submission.

Changing the bundle identifier after an app has been uploaded is not a normal version-update operation. The identifier is tied to the app's identity and App Store Connect record, so it should be selected carefully at the beginning of a project.

17. Common Errors and Troubleshooting

18. Best Practices for Managing App Identity and Versions

• Choose the Bundle Identifier early: Decide on the identifier before configuring app services and preparing the first distribution build.
• Use a consistent naming convention: Follow the same organization and application naming pattern across projects.
• Keep release versions meaningful: Use major, minor, and patch components consistently.
• Increment build numbers: Assign a new build number to each new distribution upload.
• Review all targets: Check the app and extension targets individually.
• Use source control: Track changes to project configuration and build settings.
• Separate environments carefully: Use suitable identifiers and configurations for development, staging, and production when needed.
• Verify before archiving: Confirm the active scheme, target, version, build, and signing team.
• Document release changes: Maintain a record of version updates and the changes included in each build.

19. Practical Example: Configuring a Student Learning App

Consider a student learning application called AcademyLearn. The app provides lessons, quizzes, progress tracking, and course information.

Application Configuration

Application Name: AcademyLearn
Bundle Identifier: com.justacademy.academylearn
Version: 1.0.0
Build: 1

Scenario 1: First Development Build

Bundle ID: com.justacademy.academylearn
Version: 1.0.0
Build: 1

The team creates the first working version of the app.

Scenario 2: Fixing a Login Bug

Bundle ID: com.justacademy.academylearn
Version: 1.0.0
Build: 2

The release version remains unchanged because the team is distributing another build of the same release version.

Scenario 3: Adding a Quiz Feature

Bundle ID: com.justacademy.academylearn
Version: 1.1.0
Build: 3

The application receives a minor version update because a new feature has been introduced.

Scenario 4: Releasing a Major Redesign

Bundle ID: com.justacademy.academylearn
Version: 2.0.0
Build: 4

The team releases a major update with a redesigned interface and significant functionality changes.

20. Hands-on Practice Exercise

Create a basic iOS application in Xcode and configure its identity and release information.

Tasks

1. Create a new iOS application project named MyLearningApp.
2. Set the Bundle Identifier to com.example.mylearningapp.
3. Set the Version Number to 1.0.0.
4. Set the Build Number to 1.
5. Build and run the application in the iOS Simulator.
6. Change the build number to 2.
7. Build the application again.
8. Update the version to 1.1.0 after adding a new feature.
9. Verify the values in the target's General and Build Settings sections.
10. Prepare an archive and inspect the distribution information.

Expected Result

At the end of the exercise, you should be able to configure an application's identity, update its release version, increment its build number, and verify the settings before distribution.

21. Interview Questions and Answers

Q1. What is a Bundle Identifier in iOS?

Answer: A Bundle Identifier is a unique string used by iOS and Apple's development tools to identify an application bundle.

Q2. What is the purpose of a Bundle Identifier?

Answer: It identifies an app for installation, signing, app services, and App Store distribution.

Q3. What naming convention is commonly used for Bundle Identifiers?

Answer: The reverse-domain naming convention, such as com.company.application, is commonly used.

Q4. What is the difference between Version and Build?

Answer: Version identifies a release of the application, while Build identifies a particular compiled iteration of that release.

Q5. What is CFBundleIdentifier?

Answer: It is the Info.plist key that represents the application's bundle identifier.

Q6. What is CFBundleShortVersionString?

Answer: It represents the user-facing release version of an application.

Q7. What is CFBundleVersion?

Answer: It represents the build version that identifies a particular iteration of the application bundle.

Q8. When should a developer increment the build number?

Answer: A developer should increment the build number when preparing a new build for distribution or upload, following the project's release process.

Q9. Can multiple builds have the same version number?

Answer: Yes. Multiple builds can belong to the same release version, provided each distribution build has an appropriate unique build number.

Q10. Where can you configure the Bundle Identifier in Xcode?

Answer: Select the application target, open the General tab, and locate the Identity section.

Q11. What is PRODUCT_BUNDLE_IDENTIFIER?

Answer: It is an Xcode build setting that defines the product's bundle identifier.

Q12. What is MARKETING_VERSION?

Answer: It is the Xcode build setting commonly used to manage the user-facing release version.

Q13. What is CURRENT_PROJECT_VERSION?

Answer: It is the Xcode build setting commonly used to manage the build number.

Q14. Why should the Bundle Identifier be chosen carefully?

Answer: It is associated with the application's identity, signing configuration, and App Store Connect record. Changing it after distribution can require a different app identity.

Q15. Why are version and build numbers important for TestFlight?

Answer: They help developers and testers identify the release version and distinguish individual uploaded builds.

22. Quick Revision Notes

• Bundle Identifier: Unique identity of an application.
• Version Number: User-facing release version.
• Build Number: Identifies a specific build iteration.
• CFBundleIdentifier: Info.plist key for the bundle ID.
• CFBundleShortVersionString: Info.plist key for the release version.
• CFBundleVersion: Info.plist key for the build version.
• PRODUCT_BUNDLE_IDENTIFIER: Xcode build setting for the bundle ID.
• MARKETING_VERSION: Xcode build setting for the release version.
• CURRENT_PROJECT_VERSION: Xcode build setting for the build number.
• TestFlight: Used to distribute and test beta builds.
• App Store Connect: Used to manage app records and submitted builds.

23. Conclusion

Configuring the Bundle Identifier, Version Number, and Build Number is an essential part of professional iOS application development. The Bundle Identifier establishes the application's identity, the Version Number communicates the release level, and the Build Number distinguishes individual compiled iterations.

Developers should configure these values carefully in Xcode, maintain consistent versioning practices, and verify the settings before creating archives or uploading builds to App Store Connect. Understanding these concepts helps prevent signing errors, distribution problems, and confusion during application testing and release management.

24. Additional Learning Resources

• Apple Developer Documentation – Bundle Configuration
• Apple Xcode Help – What Is a Bundle ID?
• Apple Xcode Help – Set the Version Number and Build String
• Apple Documentation – CFBundleShortVersionString
• Apple Documentation – CFBundleVersion

Continue Learning: Explore practical iOS development concepts, Xcode configuration, app signing, testing, and App Store distribution through JustAcademy's iOS Training Course.

Register for a Demo: Register for a Free Course Demo and learn more about the training program.